A Brief Discussion on Environment Name Configuration and Application in ASP.NET Core

TLDR

• ASP.NET Core distinguishes environments via the ASPNETCORE_ENVIRONMENT variable, with Development, Staging, and Production included by default.
• The configuration loading mechanism follows a "last-in-wins" approach; the system automatically loads appsettings.json followed by appsettings.{EnvironmentName}.json.
• Avoid manually reloading configuration files in Program.cs to prevent overwriting environment-specific settings.
• launchSettings.json is only applicable for local development; production environments must set environment variables via IIS (web.config) or Dockerfile.
• At runtime, you can inject IWebHostEnvironment and use extension methods like IsDevelopment(), IsStaging(), or IsEnvironment() to determine the current environment.

Environment Names and Configuration Loading Mechanism

In ASP.NET Core, the EnvironmentName environment variable is used to distinguish between different execution environments. The system provides Development, Staging, and Production values by default.

Unlike the Web.config transformation mechanism in older .NET Framework versions, ASP.NET Core adopts an appsettings.json override logic. When WebApplication.CreateBuilder(args) is executed, the system automatically loads configurations in the following order:

builder.ConfigureAppConfiguration((hostingContext, config) => {
    IHostEnvironment env = hostingContext.HostingEnvironment;
    bool reloadOnChange = GetReloadConfigOnChangeValue(hostingContext);

    config.AddJsonFile("appsettings.json", optional: true, reloadOnChange: reloadOnChange)
            .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true, reloadOnChange: reloadOnChange);
    // ...
})

WARNING

When you might encounter this issue: Manually reloading configuration files in Program.cs. Since ASP.NET Core internally handles the loading of appsettings.json and appsettings.{Environment}.json automatically, manually reloading these files in your code may cause settings to be accidentally overwritten, rendering environment variables ineffective.

Methods for Setting Environment Variables

Local Development Environment

Developers can configure the local environment via Properties\launchSettings.json. This setting will override global environment variables.

{
  "profiles": {
    "Sample": {
      "commandName": "Project",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

IIS Deployment Environment

If deploying using Visual Studio, you need to add the <EnvironmentName> tag to the XML of your Publish Profile. After deployment, the system will automatically generate the corresponding environment variable setting in web.config:

<aspNetCore processPath="dotnet" arguments=".\YourApp.dll">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Staging" />
  </environmentVariables>
</aspNetCore>

TIP

When you might encounter this issue: Attempting to exclude unnecessary configuration files. In ASP.NET Core, the legacy web.config setting <ExcludeFilesFromDeployment> is no longer effective, and you cannot exclude unnecessary appsettings.{Environment}.json files using this method.

Docker Container Environment

In a Dockerfile, you can set the environment variable directly using the ENV instruction:

FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS base
ENV ASPNETCORE_ENVIRONMENT=Staging

Determining the Environment at Runtime

If you need to execute different logic based on the environment within your code, you can inject the IWebHostEnvironment interface.

• Use built-in extension methods: IsDevelopment(), IsStaging(), IsProduction().
• Use a custom environment name: IsEnvironment("YourCustomName").

Change Log

• 2024-07-12 Initial document creation.